httpSocket provides a simple, easy way to use http (hypertext tranfer protocol). Http is the protocol that is used to view almost all web pages. httpSocket is simple to put in your project. Here's how:
1) Drag the httpSocket class into your project.
2) Make a new socket control, and change its super to "httpSocket"
And that's all you need to do to set up.
Methods
There are two ways that httpSocket lets you get files from the internet. One is through the "Download" method, and the other is through the "GetFile" method. Download is used when you want to download a file to the hard disk, and GetFile is used when you want to put the content of a file on the internet into a variable.
Would begin to download the file to the hard disk and call it "RB Release".
Events
There are several events that httpSocket has. Here they are, with explanations:
Event and parameters What it does
DLFinished (f as folderitem, txt as string, This event indicates that the file transfer is
pic as picture, filetype as string) complete. f contains the folderitem of the file
downloaded (if you used the download method), and
txt contains the text of the file (if you used the
GetFile method). If you used the GetFile method,
and the file that you requested was a picture,
then it will be contained in the pic variable.
filetype is the MIME type of the file (like
"image/gif" or "text/html")
MoreData (AmtDL as integer, This event indicates that more data has been down-
TotalSize as integer, Pct as single, loaded. AmtDL is the total amount that has been
bps as integer downloaded so far. TotalSize is the size of the
file being downloaded, and pct is the percent that
has been downloaded. If the file is 69% completed,
then pct would contain the number 0.69
Error (code as integer, msg as string) This is fired when an error occurs. Code is the
ID of the error, and msg is the default message
for that type of error.
Cancelled This is fired whenever a download is cancelled
for any reason.
ReceivedHeaders This tells you that all the headers have been
received. When this is fired, you can find out the
length of the download, it's type, and other
information the server sends.
LocationChanged (newloc as string) This is fired whenever httpSocket is told to
change the page. For an example of this, check
out espn.com. It changes to ESPN.SportsZone.com
newLoc is the new location.
PasswordNeeded (realm as string) as string This event is fired whenever you try to retrieve a
file that requries authentication. Realm is the
name of the site (which is given by the server).
You must return the name and password seperated by
a colon (e.g. "Dan V:I'm not telling"). If you
don't return anything, the "browser not
authentication compatible or authentication
failed" page will show up.
LoginFailed (URL as string) as boolean This is fired whenever an authentication attempt
fails (the wrong password/name was given). URL
contains the URL of the site. Return true if you
want to retry authentication, and return false or
nothing to display the authentication failed page.
Proxies
New in 1.3 is proxy support. This is provided through two properties: ProxyServer, which contains the server's address, and ProxyPort, which contains the port the proxy is run on.
Proxies are servers that filter web pages and graphics and THEN give them to you. They are typically used for censoring information.
The default proxy that is displayed in the example is the bess proxy.
Referers
New in 1.5 is support for referers. These are messages sent by the http server telling the client to change URLs. Open up espn.com for an example. When one of these is received, you'll want to update your URL field (if you have one). The NewLocation event is fired whenever the location changes, and it's only parameter is the new URL.
Also, if httpSocket receives 6 referers while trying to fetch one URL, it will fire the Cancelled event. This is in accordance with the RFC document on HTTP/1.1, and will prevent referer loops, where one site refers to another which refers back to the first, thus forming an infinite loop. I haven't been able to test this yet, but if you know of any loops, please tell me if this feature works.
Authentication
The main new feature in 1.6 is support for basic http authentication. In general, whenever your web browser asks you for a password, it's using basic authentication. For an example of what this is, try the popupmenu in the example project's last URL. (Use A/A as your name/pass). Whenever authentication is needed, the PasswordNeeded event is fired. Return a name and password seperated by a comma to log in. If you return nothing, then httpSocket will simply act like it can't handle passwords.
When you give httpSocket a password that doesn't work, the LoginFailed event is fired. To fire the PasswordNeeded event again, return true. To give up, simply return false or nothing.
If you want to have httpSocket send a certain name and password automatically, put the Login and Password, seperated by a colon, into the LoginAndPass property. After httpSocket retrieves a file using this name and password, it will reset them.
URL Beautification
If you type in a URL in a browser, and press return, it changes the URL so that it looks nicer (e.g. www.espn.com becomes http://www.espn.com/). If you use the FormatURL method, you are returned the formatted version of the URL you pass as a parameter. For example, msgBox httpSocket.FormatURL("www.espn.com/") would display the message "http://www.espn.com/"
Relative URLs
In a web page, links are usually expressed in relative format. For example, if the page that a link is on was located at www.rb.com/index.html, the link would simply point to purchase.html, not www.rb.com/purchase.html. Relative URLs can also be more complex if they use the ".." directory. For example, if the base path was www.nd.edu/10/9/8/7.html, the relative URL "../../../index.html" would point to www.nd.edu/index.html.
Anyway, if you use the GetRelURL(baseURL as string, relURL as string) method, it returns a complete, absolute URL based on the baseURL, and the relative one. For an example of this, look at the "Page Info" dialog.
Headers
Whenever httpSocket requests a file, it is given lots of info about the file and the server. It's usually given the file's length, type, and modification date. Other things that it's given could include the program that the server is running. Anyway, to access these, you can use the HeaderNam() and HeaderVal() arrays. The string in HeaderNam is the name of the property, and the corresponding string in HeaderVal is it's value. For example, if the server was running Apache (an http server for UNIX), HeaderNam(2) could be "Server" and HeaderVal(2) would be "Apache". The "ReceivedHeaders" event is fired whenever the headers are completely received. Check out the info dialog in the example to see how this works.
Posting Forms
Whenever you click a Submit button in a web browser, the browser submits a modified request to the server that includes the information that you're submitting. There are two methods for doing this: Get and Post. They're both similar, but a web page specifies which one to use, and most CGIs also tell you this.
To set the posting method, simply change httpSocket's Method property. You can either type httpSocket.Method=httpSocket.Post or httpSocket.Method=httpSocket.Get. This defaults to Get, which is used to fetch most web pages.
The data which you post must also be specially encoded. To do this, you can use httpSocket's URLEncode method, which takes two strings, and returns a string. Both strings are chr(13) delimited lists. The first string contains the names of the various controls, and the second string contains their content. In the DR2 version, these are arrays. The string that it returns is the URL-Encoded version of those arrays. To make httpSocket submit this, set its PostData property to whatever is returned by URLEncode. That may seem rather complex, but it's really not. Here's a short example:
That code would post my name and email to the cgi file that I specified (which of course, doesn't exist). After the data is posted, the PostData property reverts back to nothing.
You can also set the PostData property without using the URLEncode method, but you'll have to have the data encoded in some way. Also, you can change the PostEncType property to set what encoding is used. The default of "application/x-www-form-urlencoded" will work fine in almost every case though.
For a practical example, choose "Submit Form" from the File menu in the example project. The default settings will search MacAddict Magazine's archives for whatever you want. An even better example is available if you choose "Translation" from the file menu.
Client Names
Every program that uses http has a name that it goes by. This name must not contain any spaces, and includes a slash followed by the version number (w/ no letters or decimal points after it). For example, the name for previous version of httpSocket was "RealBasicClient/1 (Macintosh)".
New in 1.5 is the ability to set this yourself using the "SetClientName(name, version)" method. The first parameter is the name of the client (such as My Web Browser), and the second parameter is a number that represents the version, such as 4.0. httpSocket automatically makes this a valid client name, and uses it for retrieving data. If you don't specify a client name, it will use the default of "RBhttp/15".
MIME types
Every file that is retrieved using http is given what is called a MIME type. This identifies what type of file is being sent. For example, if the file was plain text, the MIME type would be "text/plain", and httpSocket would set the file's creator to ttxt (Simple Text).
However, I can't possibly account for every MIME type in existance. So, if your program needs to use other types besides the ones that are included by default (Text, GIF, JPEG, QuickTime, AVI, MPEG, and AIFF), then you can add your own. To do this, you must use the AddMIME MIMEtype as string, MacType as string, MacCreator as string method. the MIMEtype parameter is the file type sent by the server (e.g. "image/jpeg"). MacType and MacCreator are the Type and Creator codes that will be assigned to the downloaded file. Look at the Open event of the actual httpSocket class for an example of how to do this.
Data Size Formatting
Using the FormatSize(amt as single) as string will return a formatted size in bytes, kilobytes, or megabytes, depending on amt. Amt is the number of bytes. For example, if you wrote the code msgbox httpSocket.FormatSize(1024) it would display a message with "1.0K" in it on the screen. The example project's MoreData event uses this.
Other stuff
In early versions, the MoreData event was called whenever more data was received (how fitting╔). However, this wasn't always a good thing, because it was usually fired before a label control could completely refresh itself (making for very icky status bars). With version 1.1, I added a new property to the socket called "MoreDataLimit" This is an integer value in ticks (60ths of a second) that indicates how much time there must be between MoreData events. In the example, MoreDataLimit is set to 30 (1/2 of a second).
If you prefer to learn by examples, and not manuals, just open up the sample project╤it's very useful, and shows most of the capabilities of httpSocket.
Contact Info
If you find any server incompatibilities or bugs with httpSocket, please tell me. Almost all the bug fixes that httpSocket has ever had are direct results of people complaining. My e-mail address is dantheox@aol.com. Also, if there are any reasonable (an HTML viewer is NOT reasonable) requests for features you'd like to see in a new version of httpSocket, please tell me, and I'll consider adding them.
Legal Mumbo Jumbo - What would be complete without it?
╩╩httpSocket is in the public domain. You may modify the class, and use it however you like, as long as you give me some sort of credit (just say something like "HTTP Socket Architecture: Dan Vanderkam" in the about box). If you make any major improvements to httpSocket, be sure to tell me about them, so that everyone can benefit from them.
Version History
1.8 - Added compatibility with DR2 sockets (ie, renamed "Open" to "httpSocket"). Added the ability to GET/POST forms, which includes the PostData property, PostEncType property, URLEncode method, and Method property. Updated the manual so that "this release" no longer means 1.1. =) Added Language Translation sample to the example project. Created seperate DR2 and 1.x versions (using nothing but OneClick, Simpletext, and RB), and added the "DR2 notes" file.
1.7 - Added the "Legal Mumbo Jumbo" section of this document, the "FormatSize" method, infinite referer loop prevention, custom MIME type support, and compatibility with more types of servers. Also fixed a major bug with documents downloaded that used referers, which involved the documents being joined together. Removed a major violation of HTTP/1.1 standards which was causing some servers to have trouble with httpSocket. httpSocket now blocks the SendComplete event to avoid confusion. Added the LoginAndPass property.
1.6 - Added support for basic http authentication, and added the PasswordNeeded and LoginFailed events to go with it. Fixed a few bugs in the example project, and modified it to work with authentication.
1.5 - Complete rewrite. This means that I can update it more easily, since I wrote everything in it. Also added complete support for referers, the FormatURL command, ReceivedHeaders event, the Error event, the HeaderNam() and HeaderVal() properties for accessing headers, and added an open event so that you can use it in your controls (it wasn't present in previous versions). Fixed bug where portions of the page near the top would be chopped off. Added support for custom client names. Added GetRelURL method, and its lousy explanation. Changed names of some of the parameters in the MoreData event for no reason, so I can be more like James Milne =).
1.3 - Added support for proxies. Updated the example to work better with pages that don't tell you their size. Fixed spelling of "Download" in some places. Fixed bug where 100% would be shown as 00%.
1.2 - Added the pic property to the DLFinished event. Updated the example project to accomodate graphics. Made the name universally "httpSocket", not a mix between that and "HttpSocket".
1.1 - Added bps parameter to MoreData event. Added MoreDataLimit variable, and updated the readme and example project with these two new features.
